Accessing Objects Through Iterators (OD PG)

Inside Macintosh: OpenDoc Programmer's Guide / Part 2 - Programming: Chapter 11 - OpenDoc Runtime Features

Accessing Objects Through Iterators
The OpenDoc class library implements over ten iterator classes, which you can use to access collections of OpenDoc objects such as facets, windows, and drag items. In addition, OpenDoc defines the interface for an iterator that you must subclass in all cases (ODEmbeddedFramesIterator), and one that you must subclass only if you create a focus module for a nonexclusive focus (ODFocusOwnerIterator).
All OpenDoc iterator classes share certain characteristics, and you can use them all in a similar fashion. The iterators that you implement should also function in the same manner. For example, all iterators have at least these three methods:

First
Begins the iteration: sets your position to the first element in the collection and returns the element at that position.
Next
Advances your position in the collection by 1 and returns the element at your new position.
IsNotComplete
Returns kODTrue if the element at your current position is valid; returns kODFalse if your current position is beyond the last element in the collection.
Some iterators also have these methods:

Last
Returns the final element in the collection.
Previous
Returns the element in the collection prior to the one at your current position.
For most iterators, the First and Next methods return their collection items as function results; for some, the collection items are returned in output parameters.
Some iterators allow you to traverse the collection in either direction (beginning to end or end to beginning). For those iterators, the direction is an invariant; once the iteration has begun, you can't change direction. If you are traversing the collection from the beginning to the end, you call First followed by a series of calls to Next; in this case you cannot call Previous. If you are traversing the collection from the end to the beginning, you call Last followed by a series of calls to Previous; in this case you cannot call Next.
You can set up an iteration in several ways. A common method is to set up a for loop that uses the IsNotComplete method to test for completion.
ODFrameFacetIterator* iter = frame->CreateFacetIterator(ev);
for (ODFacet* facet = iter->First(ev); iter->IsNotComplete(ev);
      facet = iter->Next(ev))
{
   //...perform the task of the iteration
}
Alternatively, you can use a while statement to test for completion.
ODFrameFacetIterator* iter = frame->CreateFacetIterator(ev);
ODFacet* facet = iter->First()
while (iter->IsNotComplete())
{
   //...perform the task of the iteration
   facet = iter->Next(ev);
}
A third possibility--if the Next method returns its item as a function result and if it consistently returns a null value for a nonexistent element--is to use that method itself to test for completion.
ODFrameFacetIterator* iter = frame->CreateFacetIterator(ev);
while ((facet = iter->Next(ev)) != kODNULL)
{
   //...perform the task of the iteration
}
OpenDoc iterators follow these conventions:

You can call Next without first calling First. If you do, your first call to Next is the same as a call to First.
You must call either First or Next before calling IsNotComplete. If you do not, IsNotComplete generates the exception kODErrIteratorNotInitialized.
For an empty collection, First and Next return kODNULL (if that type of iteration returns its information in the function result), and IsNotComplete returns kODFalse.
If IsNotComplete returns kODTrue, the last item obtained is valid.
If IsNotComplete returns kODFalse (at the end of the iteration), a subsequent call to Next returns kODNULL (if that type of iteration can return null values).
If the collection is modified while an iteration is in progress, calling any of these iterator methods generates the exception kODErrIteratorOutOfSync.